package itsm.isperp.framework.upload;

import itsm.isperp.framework.domain.UploadInfo;

import java.io.IOException;
import java.io.InputStream;
import java.sql.SQLException;
import java.util.Collection;

import javax.servlet.http.HttpServletRequest;

/**
 * 对上传的文件进行保存.
 */
public interface UploadPersister {

	/**
	 * 对文件进行保存.
	 * 
	 * @param inputStream
	 *            文件输入流
	 * @param fileName
	 *            文件名称
	 * @param store
	 *            文件存储位置
	 * @param contentType
	 *            文件内容类型
	 * @return 返回UploadInfo对象
	 * @throws Exception
	 */
	public UploadInfo persist(InputStream inputStream, String fileName,
			String store, String contentType) throws Exception;

	/**
	 * 对上传的文件进行保存.
	 * 
	 * @param request
	 *            包含上传请求的HttpServletRequest对象
	 * @param uploadPreference
	 *            上传属性,包含了如存储位置,大小限制等信息
	 * @throws IOException
	 *             当进行文件流相关的操作时可能抛出此异常,这通常表示文件上传错误或文件保存错误
	 * @throws SQLException
	 *             当利用LobStoreService将文件保存到数据库中时可能抛出此异常
	 */
	public void persist(HttpServletRequest request,
			UploadPreference uploadPreference) throws IOException, SQLException;

	/**
	 * 根据主键获取已上传文件的信息.
	 * <p>
	 * 作为参数的主键通常保存在业务数据中.<br/>
	 * <strong>注意:如果您通过设置fetchContent的值为true取得了输入流,请一定记得将其关闭.</strong>
	 * </p>
	 * 
	 * @param id
	 *            代表已上传文件的主键
	 * @param fetchContent
	 *            是否读取上传文件的内容,如果为true,则可通过作为返回值的UploadInfo对象的getContent函数取得输入流
	 * @return 已上传文件的信息
	 * @throws IOException
	 *             当将上传的文件作为输入流返回时可能抛出此异常
	 * @throws SQLException
	 *             当从数据库中读取文件信息时可能抛出此异常;此外,使用LobStoreService从数据库中获取文件内容时也可能抛出此异常
	 */
	public UploadInfo get(String id, boolean fetchContent) throws IOException,
			SQLException;

	/**
	 * 根据文件名找到所有的上传文件信息
	 * 
	 * @param name
	 *            上传时真实文件名
	 * @param fetchContent
	 *            是否一起取文件内容
	 * @return 与给定文件名匹配的所有的上传文件信息
	 */
	Collection<UploadInfo> getUploadInfosByName(String name,
			boolean fetchContent) throws IOException, SQLException;

	/**
	 * 根据主键删除一个已上传的文件.
	 * <p>
	 * 此操作将同时删除上传的文件内容及其信息.
	 * </p>
	 * 
	 * @param id
	 *            代表已上传文件的主键
	 * @throws IOException
	 *             当从文件系统删除文件内容时可能抛出此异常
	 * @throws SQLException
	 *             当从数据库删除文件信息及文件内容时可能抛出此异常
	 */
	public void delete(String id) throws IOException, SQLException;
}
